feat(agents): harness-agnostic effort write-side + spawn legacy bridge (Goose + Claude Code) - #4625

Summary

Genericizes the agent effort write-side so non-Buzz runtimes (Goose and Claude Code) participate in the same canonical effort contract as buzz-agent, with a spawn bridge that translates the canonical key to whatever the target harness expects at launch time.

Five commits on top of main (cb4a73e17).

Phase 1 — B-collapse + ACP identity + alias normalization

desktop/src-tauri/src/managed_agents/config_bridge/

• B-collapse for same-value live effort. Previously a live thought_level option whose raw value equalled the global default was reported as a live override instead of collapsing to GlobalDefault. Fixed: compare via normalized values after applying effort_norm.
• thought_level ACP identity. When both thought_level and thinking_effort ACP categories are present, thought_level wins. The winning entry's config_id is captured and forwarded to write_via; it is always entry-supplied, never hardcoded.
• ACP effort normalization. The selected ACP option's value is normalized through effort_norm before candidate-list construction and B comparison. An invalid ACP value (e.g. minimal for Goose) is omitted as a value candidate so a lower tier wins; write_via stays AcpSetConfigOption with the entry-supplied config_id because the route targets the option, not its current value.
• Alias normalization (TS). normalizeEffortValue in buzzAgentConfig.ts uses the runtime-supplied effortAliases descriptor as the single normalization authority. Absent effortAliases means no aliases — the built-in Goose fallback table has been removed. Canonical values pass through; unrecognised values return null.

Phase 2 — Canonical effort contract + native-key persistence + mutation contract

desktop/src/features/agents/

Single read policy. resolveEffortFromEnv(envVars, nativeKey, legacyKey, acceptedValues, effortAliases) in agentConfigCore.ts is the authoritative read path for all effort surfaces. It normalizes, applies native-first / valid-legacy-fallback, and returns { value, legacyConsumed }. deriveAgentConfigFieldModel, HarnessNativeEffortFields, and both editors' legacyEffortConsumed memos all call it.

Descriptor. deriveAgentConfigFieldModel emits an effort field with:

• optionSource: "harnessNative" for runtimes with a static acceptedEffortValues vocabulary (Goose, Claude Code); "buzzAgentCatalog" for buzz-agent; "legacyProviderModelCatalog" otherwise.
• acceptedEffortValues from runtime metadata — never the seven-value buzz-agent list.
• Legacy fallback (legacyKey = BUZZ_AGENT_THINKING_EFFORT) at record/persona scope only; omitted at global/onboarding (Delta 5: that key is buzz-agent's own native key there).

UI surfaces. AgentConfigFields (global/onboarding), PersonaAdvancedFields (persona/definition), and EditAgentAdvancedFields (record/instance) all branch on optionSource === "harnessNative". For harness-native runtimes they render HarnessNativeEffortFields with runtime metadata; EffortSelectField receives canonical choices from acceptedEffortValues, not the Buzz catalog.

HarnessNativeEffortFields. Accepts legacyEnvKey: string | null (required — null at global/onboarding enforces the tier boundary and prevents silent legacy key deletion). Reads via resolveEffortFromEnv. Save = canonical native write + atomic legacy delete at record/persona scope; native-key-only at global scope (preserves coexisting foreign native keys — Delta 5).

applyHarnessNativeEffortChange. Exported production mutation helper called by both the component and AgentConfigFields's onChange. Encodes the scope-split policy: legacyKey = BUZZ_AGENT_THINKING_EFFORT at record/persona; legacyKey = null at global. Tests import and exercise it directly.

Model-coupled mutation guard. Heal-on-mount, orphan-clear, and useEffortAutoClear in AgentConfigFields skip the native effort key when isHarnessNativeEffort. Goose and Claude Code effort is model-independent — their vocabularies are static; the reader's skip-as-absent contract handles invalid values non-destructively. The useEffortAutoClear hook receives "" as currentEffort for harness-native runtimes, making it a no-op.

Inherit-transition strip. resolveInheritedRuntimeSubmission accepts excludePersonaEnvKeys to strip effort keys from the persona merge layer on a pinned→inherit transition. AgentInstanceEditDialog passes [thinkingEnvVar, ...allKnownEffortKeys(runtimes)] when the runtime has thinkingEnvVar — derives the known-key set from the catalog, not a static constant.

Legacy row visibility. legacyConsumedKey controls advanced-row suppression. The legacy row is hidden only when the key was validly consumed; invalid or unrecognised legacy values remain visible as advanced env rows.

Phase 3 — Shared alias resolver + spawn effort bridge + deploy test

desktop/src-tauri/

effort_tier_alias. managed_agents/config_bridge/mod.rs exposes effort_tier_alias(value, accepted_values, allow_legacy_alias) — the shared normalizer used by build_thinking_field and apply_effort_bridge. The boolean parameter is allow_legacy_alias with an explicit per-tier doc table (record: true, persona: true, global: false, definition: false, baked: false) so no tier can silently diverge.

apply_effort_bridge. managed_agents/config_bridge/mod.rs bridges canonical effort onto the spawn payload:

• Strips all known foreign effort keys using all_known_effort_keys() (derived from KNOWN_ACP_RUNTIMES::thinking_env_var, not a static constant).
• Resolves the canonical winner from all tiers: record native → record legacy → persona native → persona legacy → global native → definition native → baked native.
• Baked tier is native-key-only (no legacy alias); baked xhigh normalizes to max; invalid baked values skip as absent.
• Definition tier uses allow_legacy_alias=false — mirrors the reader's contract (plan v3 Delta 2).
• Writes to launch_config.launch.env for deploy/cloud agents; top-level env_vars is left unbridged.

One metadata contract. EffortNormalization.aliases is serialized through AcpRuntimeCatalogEntry.effort_aliases in discovery.rs and surfaced through RawAcpRuntimeCatalogEntry / AcpRuntimeCatalogEntry in TS. normalizeEffortValue uses the descriptor-supplied alias table; absent effortAliases means no aliases (not Goose aliases). All production call sites pass the descriptor: AgentConfigFields via resolveBakedEffort, both dialogs via useAgentDialogDefaults(runtime: ...), HarnessNativeEffortFields via normalizeEffortValue(raw, acceptedEffortValues, effortAliases). The static ALL_KNOWN_EFFORT_KEYS constant (Rust and TS) is replaced by all_known_effort_keys() / allKnownEffortKeys(runtimes) derived from runtime declarations — adding a runtime automatically participates in foreign-key stripping without touching a constant.

Baked-effort display. resolveBakedEffort(bakedEnv, nativeKey, runtime) in bakedEnvHelpers.ts is the shared resolver for every baked-effort display surface: AgentConfigFields (global/onboarding) and getInheritedAgentDefaults. Both normalize through alias→canonical / invalid→absent so display parity with spawn is maintained. useAgentDialogDefaults gains a runtime param; callers pass runtime: runtimes.find(...) or runtime: prospectiveRuntime in one line rather than three separate props.

Phase 4 — Claude Code effort enablement

desktop/src-tauri/src/managed_agents/discovery/ + desktop/src/features/agents/lib/

Catalog declaration. CLAUDE_EFFORT_NORMALIZATION added in runtime_metadata.rs with canonical vocabulary low | medium | high | xhigh | max and no aliases (Claude Code accepts these natively; xhigh is canonical, not an alias as it is for Goose). The auto value is deliberately excluded — unset env already means model-default. Available levels are per-model, but Claude Code falls back to the nearest supported level, so a static vocabulary declaration is safe.

Catalog wiring. The claude entry in KNOWN_ACP_RUNTIMES now declares thinking_env_var: Some("CLAUDE_CODE_EFFORT_LEVEL") and effort_normalization: Some(&CLAUDE_EFFORT_NORMALIZATION). The env var is inherited by the claude-agent-acp Node.js adapter process from Buzz's spawn env, which passes it through process.env to the underlying SDK subprocess env and then to the claude CLI binary.

UI policy removal. The else if (runtime?.id === "claude") deferral branch (render: "deferredUntilNativeOptionsAvailable") in agentConfigCore.ts is removed. Claude now hits the existing if (runtime?.thinkingEnvVar) path and emits a harnessNative descriptor with render: "control" — zero new UI code.

Test coverage

• Rust: ACP B-collapse, thought_level priority, ACP alias/case/invalid normalization, alias resolver tiers, bridge descriptor hygiene, deploy parity boundary; baked tier (high/xhigh→max/minimal→absent/legacy-excluded/beaten-by-record); definition tier (legacy excluded, native accepted) in both spawn and reader; Claude Code catalog vocabulary/no-alias pins, spawn native survival, invalid-value skip, foreign-key stripping, legacy alias at record tier (valid and invalid-for-Claude cases).
• TS: resolveEffortFromEnv read policy (native-first, legacy fallback, tier boundary, null-legacyKey); applyHarnessNativeEffortChange scope-split mutation; deriveAgentConfigFieldModel at global/definition/instance scope; HarnessNativeEffortFields legacy migration; excludePersonaEnvKeys inherit-transition strip; isHarnessNativeEffort guard (xhigh survives model-heal; minimal survives; buzz-agent auto-clear unchanged); inherited-defaults normalization (global xhigh→max, baked xhigh→max, baked minimal→absent); global coexisting native-pair preservation; resolveBakedEffort direct pins (xhigh→max, minimal→null — the production helper used by global/onboarding); normalizeEffortValue absent-aliases pin and non-Goose ultra→max pin (TS normalization comes from supplied descriptor, not any runtime-specific table); Claude Code harnessNative descriptor shape, valid values pass-through, Goose aliases absent from Claude vocab.

Deferred

• useAgentDialogDefaults retains three unused optional inputs (nativeEffortKey, acceptedEffortValues, effortAliases) superseded by the runtime param. Follow-up cleanup: remove them and require runtime.